home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / blankery / xsb / xsb.doc < prev    next >
Text File  |  1992-06-26  |  4KB  |  108 lines
  1.  
  2.         The eXternal Screen Blanker Library Standard V1.0
  3.         -------------------------------------------------
  4.  
  5.           Written by Oliver Wagner, placed in the Public Domain
  6.  
  7.         Contact: o.wagner@aworld-2.zer[.sub.org]
  8.  
  9. 1. Purpose
  10. ----------
  11. XSB  is  a  defined standard for fancy screen blankers.  It allows the easy
  12. implementation  of  blanking  effects  without  worrying  about the blanker
  13. commodity  itself.   Also,  it allows sharing a screen blanking effect with
  14. several different blankers supporting the XSB standard.
  15.  
  16. A  simple  screen  blanking  commodity  --  XSBCX  --  is  included  in the
  17. distribution package.
  18.  
  19. If  you  think that is complete nonsense, usefull and a waste-of-time, then
  20. you maybe correct.
  21.  
  22. 2. Credits
  23. ----------
  24. Credits go to Christoph Teuber, Sandro Paolini and Holger Lubitz who helped
  25. to work out the original idea.
  26.  
  27. 3. Implementation
  28. -----------------
  29. A  XSB  library simply consists of three entry points.  The library will be
  30. loaded  by  the blanking commodity, and will be run on the commodity's task
  31. schedule.
  32.  
  33. The entry points are:
  34.  
  35.  
  36.  
  37.     void XSBBlankScreen(long sigmask,struct XSBInfo *xsi) (-30 XSBBase)
  38.                 D0        A0
  39.  
  40.     The main blanking entry point. The XSB commodity will call this
  41.     routine when it is time to blank the screen.
  42.  
  43.     "sigmask" is a exec signal bit (already converted to a mask)
  44.     which is used by the commodity system to signal that the
  45.     blanking effect should quit and restore the original screen
  46.     display. You can do a "Wait(sigmask)" or so to find out when the
  47.     user is doing input again.
  48.  
  49.     "xsi" is a structure created by the calling commodity for your
  50.     convinience. The structure is defined as
  51.  
  52.      struct XSBInfo {
  53.       struct timerequest *tr;
  54.       struct XSBPref *prefs;
  55.      };
  56.  
  57.     "tr" is a pointer to a ready-to-use timerequest (UNIT_VBLANK),
  58.     opened by the calling commodity. Use it to delay your actions.
  59.  
  60.         NEVER DO A BUSY LOOP INSIDE YOUR BLANKING EFFECT!
  61.  
  62.     "prefs" is a pointer to an array of XSBPref structures, loaded
  63.     from the file "ENV:XSB/<blankername>.XSBP". The contents of
  64.     the XSBPref structures are defined by you. If no prefs file
  65.     was found, "prefs" will be NULL. See the XSBGetParams() call
  66.     for more information on XSB preferences.
  67.  
  68.  
  69.  
  70.     char *XSBGetID(void) (-36 XSBBase)
  71.      D0
  72.  
  73.     This call simply returns a string giving information about
  74.     the blanking effect created by the library. It will be display
  75.     by the calling commodity upon the user's request, normally
  76.     by the EasyRequest() or a similar function. That means that
  77.     you can include "\n"s in the text as line delimiters.
  78.  
  79.  
  80.     struct XSBParams *XSBGetParams(void) (-42 XSBBase)
  81.      D0
  82.  
  83.     This call returns a linked list of XSBParams structures, or
  84.     NULL if the blanking library doesn't support preferences.
  85.  
  86.     The structure is defined as:
  87.  
  88.      struct XSBParams {
  89.       struct XSBParams *next;
  90.       long type; /* see defines below */
  91.       char *text; /* text label for gadgets */
  92.       char **labels; /* optional labels for cycle gadgets */
  93.       long min,max; /* optional min/max values for sliders */
  94.       struct XSBPref *value; /* value entry */
  95.      };
  96.  
  97.     Upon the user's request, the calling commodity will build a
  98.     preference requester with the items described by the 
  99.     XSBParams structures. The user than may manipulate the items,
  100.     save or cancel the changes. Overflow checking must be done
  101.     by the library. A maximum of 10 preference items are supported.
  102.     The XSBPref structures should belong to the libraries private
  103.     data space and should be initialized at loading time.
  104.  
  105.     See the provided include file, "xsb.h", and the provided
  106.     example library for more information about using the XSB
  107.     preference system.
  108.